<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Migrating to client-side windows</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<link rel="home" href="index.html" title="GTK+ 2 Reference Manual">
<link rel="up" href="migrating.html" title="Part IV. Migrating from Previous Versions of GTK+">
<link rel="prev" href="gtk-migrating-label-links.html" title="Migrating from SexyUrlLabel to GtkLabel">
<link rel="next" href="pt05.html" title="Part V. GTK+ Tools">
<meta name="generator" content="GTK-Doc V1.18 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
<td><a accesskey="p" href="gtk-migrating-label-links.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="migrating.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">GTK+ 2 Reference Manual</th>
<td><a accesskey="n" href="pt05.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr></table>
<div class="chapter">
<div class="titlepage"><div><div><h2 class="title">
<a name="gtk-migrating-ClientSideWindows"></a>Migrating to client-side windows</h2></div></div></div>
<p>
    In version 2.18, GDK has been changed to use client-side windows. This
    means that there is no longer a 1-1 correspondence between <a href="../gdk/gdk-Windows.html#GdkWindow"><span class="type">GdkWindows</span></a>
    and windows in the underlying window system. In particular, it is no
    longer correct to assume that each window has an associated XID.
    Code that makes this assumption can sometimes be fixed by calling
    <a href="../gdk/gdk-Windows.html#gdk-window-ensure-native"><code class="function">gdk_window_ensure_native()</code></a> on the windows in question.
    Calling <a href="../gdk/gdk-X-Window-System-Interaction.html#gdk-x11-drawable-get-xid"><code class="function">gdk_x11_drawable_get_xid()</code></a> (or <a href="../gdk/gdk-X-Window-System-Interaction.html#GDK-WINDOW-XID:CAPS"><code class="function">GDK_WINDOW_XID()</code></a>) from the
    X11-specific API on a non-native window will explicitly call
    <a href="../gdk/gdk-Windows.html#gdk-window-ensure-native"><code class="function">gdk_window_ensure_native()</code></a>, so old code using this will continue to
    work. A small gotcha is that the <a href="../gdk/gdk-X-Window-System-Interaction.html#GDK-WINDOW-XID:CAPS"><code class="function">GDK_WINDOW_XID()</code></a> call is no longer a
    trivial accessor for the XID of the window, and thus must not be called
    from another thread without taking locking precautions.
  </p>
<p>
    GDK looks for the <code class="envar">GDK_NATIVE_WINDOWS</code> environment variable
    and makes all windows native if it is set. It also tries to be more
    compatible with the way prior versions worked in some other ways.
  </p>
<p>
    Some applications assume that they can just operate on the X windows
    corresponding to their GDK windows without ever telling GDK. One
    example that we've seen is changing the child window stacking order
    using <code class="function">XRestackWindows()</code>. Fixing this properly requires to fix the code
    to use GDK functions to achieve whatever it is trying to achieve.
    To make this easier in the case of stacking order changes, we've added
    a <a href="../gdk/gdk-Windows.html#gdk-window-restack"><code class="function">gdk_window_restack()</code></a> function.
  </p>
<p>
    One change that can cause problems for some applications is that GDK
    is more aggressive about optimizing away expose events. Code that does
    more than just repainting exposed areas in response to expose events
    may be affected by this.
  </p>
<p>
    Problems can also occur when using cairo for drawing. One thing that can
    go wrong is clip handling. If you ever need to reset the clip region on
    a cairo_t (i.e. use <a href="/usr/share/gtk-doc/html/cairo/cairo-cairo-t.html#cairo-reset-clip"><code class="function">cairo_reset_clip()</code></a>), you have to to use
    <a href="../gdk/gdk-Cairo-Interaction.html#gdk-cairo-reset-clip"><code class="function">gdk_cairo_reset_clip()</code></a> instead. The reason for this is that the <a href="/usr/share/gtk-doc/html/cairo/cairo-cairo-t.html#cairo-reset-clip"><code class="function">cairo_reset_clip()</code></a> call will remove the initial clip region that limits your drawing to
    the client-side window at hand, so you will end up drawing over stuff
    outside the window. You also need to use <a href="../gdk/gdk-Cairo-Interaction.html#gdk-cairo-reset-clip"><code class="function">gdk_cairo_reset_clip()</code></a> if you
    use a cairo_t that was not allocated in a double-buffered expose handler
    and keep it in use after window hierarchy changes (resizing, moving,
    stacking order changes). The easiest fix for this kind of problem is to
    simply create a new cairo context for each expose event.
  </p>
<p>
    Due to a weird API in XClearArea the <a href="../gdk/gdk-Windows.html#gdk-window-clear-area"><code class="function">gdk_window_clear_area()</code></a> call handled
    a specified width or height of zero to mean "to end of window" for
    non-double-buffered drawing. This has been changed to be consistent with
    the docs and what happens in the double-buffered case. All code in GTK+
    that relied on this has been fixed, but it is possible (although unlikely)
    that third party applications rely on this. If you need to do this, just
    implement it yourself using <a href="../gdk/gdk-Drawing-Primitives.html#gdk-drawable-get-size"><code class="function">gdk_drawable_get_size()</code></a>.
  </p>
</div>
<div class="footer">
<hr>
          Generated by GTK-Doc V1.18</div>
</body>
</html>